%% This file is part of Enblend.
%% Licence details can be found in the file COPYING.


\section[Interacting with \App\commonpart]{\label{sec:interaction}%
  \genidx[\rangebeginlocation]{interaction with \App}%
  Interacting with \App\commonpart}

This section explains how to find out about the inner workings of \emph{your} version of \App{}
without looking at the source code.  And it states how to interact with \App{} besides passing
command-line options and image filenames.


\subsection[Finding Out Details]{\label{sec:finding-out-details}%
  \genidx{detailed configuration}%
  Finding Out Details About \app}

An \appcmd{} binary can come in several configurations.  The exact name of the binary may vary,
and it may or may not reflect the ``kind of \app''.  Therefore, \appcmd{} offers several options
to query exactly\dots

\begin{compactitemize}
\item
  what its exact version number is (see \sectionabbr~\fullref{sec:exact-version} and
  option~\flexipageref{\option{--ver\shyp sion}}{opt:version}),

\item
  what features it does support (see \sectionabbr~\fullref{sec:compiled-in-features} and
  options~\flexipageref{\option{--ver\shyp sion}}{opt:version} and
  \flexipageref{\option{--ver\shyp bose}}{opt:verbose}),

\item
  which image formats it can read and write without the need of conversion (see
  \sectionabbr~\fullref{sec:image-formats} and
  option~\flexipageref{\option{--show-image-for\shyp mats}}{opt:show-image-formats}),

\item
  who built it, (see \sectionabbr~\fullref{sec:name-of-builder} and
  option~\flexipageref{\option{--show-signature}}{opt:show-signature}), and finally

\item
  what compiler and libraries were used to do so (see
  \sectionabbr~\fullref{sec:compiler-and-libraries} and
  option~\flexipageref{\option{--show-soft\shyp ware-com\shyp po\shyp
      nents}}{opt:show-software-components}).
\end{compactitemize}

The information are explained in detail in the following sections.

\subsubsection[Exact Version]{\label{sec:exact-version}%
  \genidx{version!software}%
  \gensee{software version}{version, software}%
  \genidx{version!query}%
  \gensee{query version}{version, query}%
  \optidx{--version}%
  Exact Version Number}

\exampleName~\ref{ex:option-version} shows a possible output of \sample{\app{} --version}.  The
version number at the beginning of the text tells about the \emph{exact} version of the binary.
It is the number that can be compared with the version number of this document, which by the way
is \val{val:VERSION}.  Our slightly cranky markup (see also
\flexipageref{Notation}{sec:notation}) dispels copy-paste errors.

\begin{exemplar}
  \begin{terminal}
    \$ \app{} --version \\
    \app{} 4.2-02c1f45857b4 \\
    ~ \\
    Copyright (C) 2004-2009 Andrew Mihal. \\
    Copyright (C) 2009-2015 Christoph Spiel. \\
    ~ \\
    License GPLv2+: GNU GPL version 2 or later <http://www.gnu.org/licenses/gpl.html> \\
    This is free software: you are free to change and redistribute it. \\
    There is NO WARRANTY, to the extent permitted by law. \\
    ~ \\
    Written by Andrew Mihal, Christoph Spiel and others.
  \end{terminal}

  \caption[Output of \sample{\app{} --version}]%
          {\label{ex:option-version}%
            Example output of \appcmd{} when called with option~\option*{--version}.}
\end{exemplar}

\genidx{branches of \App\slash\OtherApp!development}%
\gensee{development branch}{branches, development}%
\gensee{development branch}{branches, development}%
The version indicator consist of a two (major and minor version) or three (major and minor
version plus patch-level) numbers separated by dots and an optional hexadecimal identifier.
Binaries from the ``Development Branch'' are assigned two-part version numbers, whereas a
three-part version number is reserved for the ``Stable Branch'' of development.  Officially
released versions lack the hexadecimal identifier.

\noindent Examples:

\begin{codelist}
\item[4.1.3-0a816672d475]\itemend
  Some unreleased version from the ``Stable Branch'', which finally will lead to version~4.1.3.

\item[4.1.3]\itemend
  Officially released version~4.1.3 in the ``Stable Branch''.

\item[4.2-1e4d237daabf]\itemend
  Some unreleased version from the ``Development Branch'', which finally will lead to
  version~4.2.

\item[4.2]\itemend
  Officially released version~4.2 in the ``Development Branch''.
\end{codelist}

Matching the version codes is the only reliably way to pair a given binary with its manual page
(``manual page for enblend~4.2-1e4d237daabf'') and its documentation.  This document mentions
the version code for example on its
\ifhevea
Title
\else
Title Page
\fi
and the \flexipageref{Abstract}{sec:abstract}.

\genidx{public repository}%
\gensee{source code repository}{public repository}%
\gensee{code repository}{public repository}%
The twelve-digit hexadecimal \metavar{ID-CODE} is automatically generated by our source-code
versioning system, \appidx{Mercurial}\uref{\mercurialseleniccom}{Mercurial}.  Use the
\metavar{ID-CODE} to look up the version on the web in our \uref{\enblendhgcodesfnet}{public
  source code repository} or, if you have cloned the project to your own workspace, with the
command
\begin{literal}
  hg log --verbose --rev \metavar{ID-CODE}
\end{literal}


\subsubsection[Compiled-In Features]{\label{sec:compiled-in-features}%
  \genidx{features}%
  \genidx{query!features}%
  \gensee{compiled-in features}{features}%
  \gensee{extra features}{features}%
  \optidx{--version}%
  \optidx{--verbose}%
  Compiled-In Features}

Adding option~\option{--verbose} to~\option{--version} will reproduce the information described
in the previous section plus a list of ``extra features''.  Any unavailable feature in the
particular binary queried returns

\begin{literal}
  Extra feature: \dots: no
\end{literal}

whereas available features answer ``\code{yes}'' followed by a detailed report on the feature
and its connection to some library or specific hardware.
\exampleName~\fullref{ex:option-version-verbose} shows such a report.  Remember that your binary
may include more or less of the features displayed there.

\begin{exemplar}
  \begin{maxipage}
    \begin{terminal}
      \$ \app{} --version --verbose \\
        \app{} 4.2-95f1fed2bf2d \\
        ~ \\
        Extra feature: dynamic linking support: yes \\
        Extra feature: OpenMP: no \\
        Extra feature: OpenCL: yes \\
        ~~- Platform \#1:~Advanced Micro Devices, Inc., \\
        ~~~~~~~~~~~~~~~~~AMD Accelerated Parallel Processing, \\
        ~~~~~~~~~~~~~~~~~OpenCL 1.2 AMD-APP (1526.3) \\
        ~~~~* no GPU devices found on this platform \\
        ~~- Platform \#2:~NVIDIA Corporation, \\
        ~~~~~~~~~~~~~~~~~NVIDIA CUDA, \\
        ~~~~~~~~~~~~~~~~~OpenCL 1.1 CUDA 6.5.51 \\
        ~~~~* Device \#1:~max.~1024 work-items \\
        ~~~~~~~~~~~~~~~~~1047872 KB global memory with 32 KB read/write cache \\
        ~~~~~~~~~~~~~~~~~48 KB dedicated local memory \\
        ~~~~~~~~~~~~~~~~~64 KB maximum constant memory \\
        ~~~~~~~~~~~~~~~~~Extensions: \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_byte\_addressable\_store \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_fp64 \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_gl\_sharing \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_global\_int32\_base\_atomics \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_global\_int32\_extended\_atomics \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_icd \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_local\_int32\_base\_atomics \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_khr\_local\_int32\_extended\_atomics \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_nv\_compiler\_options \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_nv\_copy\_opts \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_nv\_device\_attribute\_query \\
        ~~~~~~~~~~~~~~~~~~~~~cl\_nv\_pragma\_unroll \\
        ~~Search path (expanding ENBLEND\_OPENCL\_PATH and appending built-in path) \\
        ~~~~/usr/local/share/enblend/kernels:/usr/share/enblend/kernels \\
        Extra feature: metadata (EXIF, IPTC, XMP) transfer: yes \\
        ~ \\
        Copyright (C) 2004-2009 Andrew Mihal. \\
        Copyright (C) 2009-2015 Christoph Spiel. \\
        ~ \\
        License GPLv2+:~GNU GPL version 2 or later <http://www.gnu.org/licenses/gpl.html> \\
        This is free software: you are free to change and redistribute it. \\
        There is NO WARRANTY, to the extent permitted by law. \\
        ~ \\
        Written by Andrew Mihal, Christoph Spiel and others.
    \end{terminal}
  \end{maxipage}

  \caption[Output of \sample{\app{} --version --verbose}]%
          {\label{ex:option-version-verbose}%
            Example output of \appcmd{} when called with options \option*{--version}
            and~\option*{--verbose} together.}
\end{exemplar}

The \sample{--version --verbose}~combo is one of the first things test if \appcmd{} ``suddenly''
behaves strangely.

\begin{qandalist}
\item
  ``I'm running my \appcmd{} on a multi-core system, but it does not make use of it.''
  \begin{qandaanswer}
    Check for extra feature \acronym{OpenMP}.
  \end{qandaanswer}

\item
  ``My \appcmd{} complains when I call it with \sample{--gpu}!''
  \begin{qandaanswer}
    Check for extra feature \acronym{OpenCL}.
  \end{qandaanswer}

\item
  ``\appcmd{} is so slow!''
  \begin{qandaanswer}
    Ensure that \emph{neither} feature \code{mmap-view} \emph{nor} \code{image-cache} has been
    compiled in.
  \end{qandaanswer}

  \item
    ``\appcmd{} eats away too much memory!  Can I tell it to unload that onto the disk?''
    \begin{qandaanswer}
      No, there is no command-line switch for that, but you can use a version with
      \code{mmap-view}~feature.
    \end{qandaanswer}

  \item
    ``My \appcmd{} has \acronym{OpenMP} enabled.  Does it support dynamic adjustment of the
    number of threads?''
    \begin{qandaanswer}
      Under extra feature \acronym{OpenMP} look for ``support for dynamic adjustment of the
      number of threads''.
    \end{qandaanswer}

  \item
    ``My \appcmd{} has \acronym{OpenCL} enabled.  Does it need separate \acronym{OpenCL} source
    files?''
    \begin{qandaanswer}
      Under extra feature \acronym{OpenCL} look for ``Search path''.  If there is none, all
      sources have been included in the binary, otherwise the \acronym{OpenCL} source files
      should be put somewhere on the \acronym{OpenCL} search path.
    \end{qandaanswer}
\end{qandalist}


\subsubsection[Image Formats]{\label{sec:image-formats}%
  \genidx{image formats}%
  \genidx{query!image formats}%
  \optidx{--show-image-formats}%
  Supported Images Formats}

\App{} can read and write a fixed set of image formats if it was compiled to support them.  For
example the \acronym{EXR}-format requires special support libraries.  Use
option~\option{--show-image-formats} to find out

\begin{compactitemize}
\item
  what image-data formats are supported,

\item
  what filename extensions are recognized, and

\item
  what per-channel depths have been compiled into the \appcmd{} binary.
\end{compactitemize}

\noindent The only three image formats always supported are

\begin{compactitemize}
  \genidx{image formats!JPEG@\acronym{JPEG}}%
\item
  \acronym{JPEG},

  \genidx{image formats!PNG@\acronym{PNG}}%
\item
  \acronym{PNG}, and

  \genidx{image formats!TIFF@\acronym{TIFF}}%
\item
  \acronym{TIFF}.
\end{compactitemize}

\genidx{image formats!OpenEXR@\acronym{OpenEXR}}%
\noindent All others are optional.  In particular the high-dynamic range (\acronym{HDR}) format
\acronym{OpenEXR} only gets compiled if several non-standard libraries are available.

The provided per-channel depths range from just one, namely ``8~bits unsigned integral''
(\code{uint8}) up to seven:

\begin{compactitemize}
\item
  8~bits unsigned integral, \sample{uint8}

\item
  16~bits unsigned or signed integral, \sample{uint16} or \sample{int16}

\item
  32~bits unsigned or signed integral, \sample{uint32} or \sample{int32}

\item
  32~bits floating-point, \sample{float}

\item
  64~bits floating-point, \sample{double}
\end{compactitemize}

\tableName~\ref{tab:image-format-and-bit-depth} summarizes the channel bit depths of some
prominent image formats.

%% With the exception of TIFF, VIFF, PNG, and PNM all file types
%% store only 1 byte (grayscale and mapped RGB) or 3 bytes (RGB)
%% per pixel.
%%
%% PNG can store UInt8 and UInt16 values, and supports 1 and 3
%% channel images.  One additional alpha channel is also supported.
%%
%% PNM can store 1 and 3 channel images with UInt8, UInt16 and
%% UInt32 values in each channel.
%%
%% TIFF and VIFF are additionally able to store short and long
%% integers (2 or 4 bytes) and real values (32 bit float and 64 bit
%% double) without conversion.
\begin{table}
  \genidx{image formats}%
  \genidx{bits per channel}%
  \gensee{bit depth}{bits per channel}%
  \genidx{channel!alpha}%
  \genidx{profile!ICC@\acronym{ICC}}%
  \gensee{ICC profile@\acronym{ICC} profile}{profile, \acronym{ICC}}%
  \def\avail{$\bullet$}%
  \def\unava{$-$}%
  \def\unkwn{?}%
  \ifreferencemanual\begin{maxipage}\fi
  \centering
  \begin{tabular}{l cc ccccc}
    \hline
    \multicolumn{1}{c|}{} &
    \multicolumn{1}{c|}{} &
    \multicolumn{1}{c|}{} &
    \multicolumn{5}{c}{Channel Bit-Depth} \\
    \cline{4-8}

    \multicolumn{1}{c|}{Format} &
    \multicolumn{1}{c|}{Mask} &
    \multicolumn{1}{c|}{Profile} &
    \multicolumn{3}{c|}{Integral} &
    \multicolumn{2}{c}{Floating-Point} \\
    \cline{4-8}

    \multicolumn{1}{c|}{} &
    \multicolumn{1}{c|}{} &
    \multicolumn{1}{c|}{} &
    \multicolumn{1}{c|}{\code{uint8}} &
    \multicolumn{1}{c|}{\code{uint16}} &
    \multicolumn{1}{c|}{\code{uint32}} &
    \multicolumn{1}{c|}{\code{float}} &
    \multicolumn{1}{c}{\code{double}} \\

    \hline\extraheadingsep
    \acronym{JPEG}  &  \unava  &  \avail  &  \avail  &  \unava  &  \unava  &  \unava  &  \unava \\
    \acronym{PNG}   &  \avail  &  \avail  &  \avail  &  \avail  &  \unava  &  \unava  &  \unava \\
    \acronym{PNM}   &  \unkwn  &  \unava  &  \avail  &  \avail  &  \avail  &  \unava  &  \unava \\
    \optional{\acronym{V}}\acronym{TIFF} &
                       \avail  &  \avail  &  \avail  &  \avail  &  \avail  &  \avail  &  \avail
  \end{tabular}
  \ifreferencemanual\end{maxipage}\fi

  \caption[Image formats and bit-depths]%
          {\label{tab:image-format-and-bit-depth}%
            Bit-depths of selected image formats.  These are the maximum capabilities of the
            formats themselves, not \App's.  The ``Mask''-column indicates whether the format
            supports an image mask (alpha-channel), see also
            \chapterName~\ref{sec:understanding-masks}.  Column~``Profile'' shows whether the
            image format allows for \acronym{ICC}~profiles to be included; see also
            \chapterName~\ref{sec:color-spaces}.}
\end{table}


\subsubsection[Builder]{\label{sec:name-of-builder}%
  \genidx{name of builder}%
  \genidx{builder}%
  \genidx{query!name of builder}%
  \genidx{signature}%
  \gensee{signed binary}{signature}%
  \optidx{--show-signature}%
  Name Of Builder}

During building each \appcmd{} is automatically signed to give the users an extra level of
confidence that it was constructed by someone that they can trust to get it right.  Access this
signature with \sample{--show-signature} and \appcmd{} will print something like

\begin{literal}
  Compiled on sgctrl03 by Walter Harriman on Wed, Dec 22 2004, 16:07:22 GMT-7.
\end{literal}

\noindent where machine name, person, and date-time depend on the
build.


\subsubsection[Compiler And Libraries]{\label{sec:compiler-and-libraries}%
  \genidx{compiler}%
  \genidx{libraries}%
  \genidx{query!compiler}%
  \genidx{query!libraries}%
  \optidx{--show-software-components}%
  Compiler And Libraries Used To Build}

Sometimes \appcmd{} refuses to start or runs into trouble because the libraries supplied to it
do not match the ones it was compiled with.  Option~\option{--show\hyp soft\shyp
  ware\hyp components} can be helpful to diagnose the problem in such cases, because it shows
the version information of \App's most important libraries as they have identified themselves
during compile-time.

\genidx{OpenMP@\acronym{OpenMP}}%
Furthermore the report reveals the compiler used to build \appcmd{} along with the most
important compiler extensions like, for example, \acronym{OpenMP}.
\exampleName~\ref{ex:show-software-components} shows such a report.

\begin{exemplar}
  \begin{terminal}
    \$ \app{} --show-software-components \\
    Compiler \\
    ~~g++ 4.9.1 \\
    ~~implementing OpenMP standard of 2013-7 \\
    ~~implementing Cilk version 2.0 \\
    ~~~~without support of "\_Cilk\_for" keyword \\
    ~ \\
    OpenCL APIs \\
    ~~1.0 \\
    ~~1.1 \\
    ~~1.2  \\
    ~ \\
    Libraries \\
    ~~GSL:~~~~~~~~1.15 \\
    ~~Little CMS:~2.7.0 \\
    ~~Vigra:~~~~~~1.10.0
  \end{terminal}

  \caption[Output of \sample{\app{} --show-software-components}]%
          {\label{ex:show-software-components}%
            Output of \appcmd{} when asked to reveal the compiler that was used to build it
            along with the libraries it was linked against.}
\end{exemplar}


\subsection[Console Messages]{\label{sec:console-messages}%
  \genidx{console messages}%
  \genidx{message!console}%
  Console Messages}

\App{} is meant to read multiple images, ``montage'' them together, and finally write a single
output image.  So, any console messages either serve the entertainment desire of the user or
indicate problems.

\genidx{message!category}%
When \appcmd{} is instructed to only show information about its configuration (see
\sectionName~\fullref{sec:information-options}) the text goes to Standard~Output.  \appcmd{}
sends error and warning messages to Standard~Error.  The messages follow a fixed format.

\begin{literal}
  \app: \optional{\metavar{CATEGORY}:} \metavar{MESSAGE}
\end{literal}

\noindent where \metavar{CATEGORY} is

\begin{codelist}
  \genidx{message!category!error}%
\item[error:] A serious problem that sooner or later will lead to a program stop.  The result
  will definitely not be what the user wants -- including no output image at all, as \appcmd{}
  deletes corrupted or incomplete output images.

  Most messages drop category name~\sample{error} and plainly write \metavar{MESSAGE}:

  \begin{literal}
    enblend: input image "1.tif" does not have an alpha channel
  \end{literal}

  \genidx{return code}%
  \gensea{code}{return code}%
  If an \sample{error} actually leads to a premature termination of \appcmd, it returns code~1
  to the operating system.  On successful termination the return code is 0.

  \genidx{message!category!warning}%
\item[warning:] A problem that forces \appcmd{} to take an alternate execution path or drop some
  assumptions about the input.

  \genidx{message!category!info}%
\item[info:] No problem, just a ``nice-to-know'' information for the user.

  \genidx{message!category!note}%
\item[note:] Not a standalone \metavar{CATEGORY}, but an additional explanation that sometimes
  trails messages in one of the above categories.  Errors, warnings and infos tell the causes,
  notes inform about the actions taken by \appcmd{}.  Here is an example, where a \code{warning}
  gets augmented by a \code{note}:

  \begin{literal}
    enblend: warning: input images too small for coarse mask \\
    enblend: note: switching to fine mask
  \end{literal}

  \genidx{message!category!timing}%
\item[timing:] A measurement of the execution duration and thus a sub\hyp{}category of
  \code{info}.
\end{codelist}

\noindent Sadly, not all messages can be sorted in the category scheme.

\begin{description}
  \genidx{message!debug}%
\item[Debug Messages:] Though debug messages generally come devoid of a specific form the more
  civilized of them start each line with a plus sign~\sample{+}.  Example:

  \begin{literal}
    + checkpoint: leaving channel width alone
  \end{literal}

  \genidx{message!foreign sources}%
\item[Foreign Sources:] \appcmd{} depends on various foreign software components that issue
  their own messages.  \App{} tries to catch them and press them in the category scheme, but
  some of them invariably slip through.  The most prominent members of this rogue fraction are
  the notices of \uref{\hciiwrvigra}{\acronym{VIGRA}} as for example

  \begin{literal}
    enfuse: an exception occurred \\
    enfuse: Precondition violation! \\
    \dots
  \end{literal}

  and \uref{\remotesensingorglibtiff}{LibTIFF}:

  \begin{literal}
    TIFFReadDirectory: Warning, img0001.tif: wrong data type 1 for "RichTIFFIPTC"; tag ignored.
  \end{literal}

  \genidx{message!should-never-happen@``should never happen''}%
\item[``Should-Never-Happen'':] An internal consistency check fails or a cautious routine
  detects a problem with its parameters and racks up the digital equivalent of a nervous
  breakdown.  Sometimes these messages end in the word~\sample{Aborted}.

  \begin{literal}
    terminate called after throwing an instance of '\dots' \\
    what(): \dots \\
    Aborted
  \end{literal}

  If the installation of \appcmd{} is correct, this type of message may warrant a bug report as
  explained in \appendixName~\fullref{sec:bug-reports}.
\end{description}

In very unfortunate circumstances \App{} quits because of a problem, but does not show any
message.  The output file then either does not exist or it is broken.  One known reason are
out-of-memory situations, where the process needs additional memory, but cannot allocate it and
while terminating needs even more memory so that the operating system wipes it out completely
wherever it then happens to be in its execution path.


\subsection[Environment Variables]{\label{sec:environment-variables}%
  \genidx{environment variable}%
  \gensee{variable}{environment variable}%
  \gensea{environment}{environment variable}%
  Environment Variables}

A small set of environment variables influences the execution of \appcmd.  All of them depend on
\appcmd{} having been compiled with certain features.  The hint ``(direct)'' indicates genuine
variables in \appcmd, whereas ``(implicit)'' denotes variables that control libraries that are
linked with \appcmd.

\begin{description}
  \genidx[\summarylocation]{environment variable}
  \newcommand*{\xitemspace}{\ifhevea~~\else\hspace{.667em}\fi}
  \renewcommand{\makelabel}[1]{\hspace{\labelsep}#1}
  \genidx{environment variable!CILK\_NWORKERS@\envvar{CILK\_NWORKERS}}%
  \gensee{CILK\_NWORKERS@\envvar{CILK\_NWORKERS}}{environment variable, \envvar{CILK\_NWORKERS}}%
\item[\envvar{CILK\_NWORKERS}\xitemspace (implicit)\xitemspace
  \restrictednote{\acronym{Cilk}-enabled versions only.}]\itemend
  This environment variable works for \uref{\cilkplusorg}{CilkPlus} as
  \envvar{OMP\_NUM\_THREADS} (see below) does for \acronym{OpenMP}.  It can be helpful for load
  balancing.

  \genidx{environment variable!ENBLEND\_OPENCL\_PATH@\envvar{ENBLEND\_OPENCL\_PATH}}%
  \gensee{ENBLEND\_OPENCL\_PATH@\envvar{ENBLEND\_OPENCL\_PATH}}%
         {environment variable, \envvar{ENBLEND\_OPENCL\_PATH}}%
  \genidx{OpenCL@\acronym{OpenCL}}%
\item[\envvar{ENBLEND\_OPENCL\_PATH}\xitemspace (direct)\xitemspace
  \restrictednote{\acronym{OpenCL}-enabled versions only.}]\itemend
  Search path for \uref{\khronosorgopencl}{\acronym{OpenCL}} (\filename{.cl}) source files.
  \appcmd{} will refuse to run if required \acronym{OpenCL}~source files are missing, but can be
  convinced to start by resigning \acronym{OpenCL} with \sample{--no-gpu}.  If the compiled-in
  features (see \sectionName~\fullref{sec:compiled-in-features}) do not show an \acronym{OpenCL}
  search path, \appcmd{} came with internalized \acronym{OpenCL} sources and neither needs nor
  uses \envvar{ENBLEND\_OPENCL\_PATH}.

  \ifenfuse
    \restrictednote{\application{Enfuse} only.} \command{enfuse} uses the environment variable
    \envvar{ENBLEND\_OPENCL\_PATH} as search path for User-Defined \acronym{OpenCL} Exposure
    Weighting Functions.  See \sectionName~\fullref{sec:user-defined-opencl-functions}.
  \fi

  Note that the environment variable is called \envvar{ENBLEND\_OPENCL\_PATH} for \emph{both}
  applications, even for \command{enfuse}!

  \genidx{environment variable!OMP\_DYNAMIC@\envvar{OMP\_DYNAMIC}}%
  \gensee{OMP\_DYNAMIC@\envvar{OMP\_DYNAMIC}}{environment variable, \envvar{OMP\_DYNAMIC}}%
  \genidx{OpenMP@\acronym{OpenMP}}%
\item[\envvar{OMP\_DYNAMIC}\xitemspace (implicit)\xitemspace
  \restrictednote{\acronym{OpenMP}-enabled versions only.}]\itemend
  Control whether the \uref{\openmporg}{\acronym{OpenMP}} subsystem should parallelize nested
  parallel regions.  This environment variable will only have an effect is the \acronym{OpenMP}
  subsystem is capable of dynamic adjustment of the number of threads (see explanations in
  \sectionName~\fullref{sec:compiled-in-features}).

  \begin{geeknote}
    \noindent The important hot spots in the source code override the value of
    \envvar{OMP\_DYNAMIC}.
  \end{geeknote}

  \genidx{environment variable!OMP\_NUM\_THREADS@\envvar{OMP\_NUM\_THREADS}}%
  \gensee{OMP\_NUM\_THREADS@\envvar{OMP\_NUM\_THREADS}}%
         {environment variable, \envvar{OMP\_NUM\_THREADS}}%
  \genidx{OpenMP@\acronym{OpenMP}}%
\item[\envvar{OMP\_NUM\_THREADS}\xitemspace (implicit)\xitemspace
  \restrictednote{\acronym{OpenMP}-enabled versions only.}]\itemend
  Control -- which typically means: reduce -- the number of threads under supervision of the
  \uref{\openmporg}{\acronym{OpenMP}} subsystem.  By default \appcmd{} uses as many
  \acronym{OpenMP}\hyp{}threads as there are \acronym{CPU}s.  Use this variable for example to
  free some \acronym{CPU}s for other processes than \appcmd.

  \genidx{environment variable!TMPDIR@\envvar{TMPDIR}}%
  \gensee{TMPDIR@\envvar{TMPDIR}}{environment variable, \envvar{TMPDIR}}%
\item[\envvar{TMPDIR}\xitemspace (direct)\xitemspace
  \restrictednote{\sample{mmap\_view}-branch only.}]\itemend
  \envvar{TMPDIR} determines the directory and thus the drive where \appcmd{} stores all
  intermediate images.  The best choice follows the same rules as for a swap-drive: prefer the
  fastest disk with the least load.
\end{description}


%% \subsection[External Files]{External Files
%%   \label{sec:external-files}
%%   \genidx{external files}
%%   \genidx{files!external}}

\genidx[\rangeendlocation]{interaction with \App}


%%% Local Variables:
%%% fill-column: 96
%%% End:
